Java Database Programming with JDBC Java Database Programming with JDBC
by Pratik Patel
Coriolis, The Coriolis Group
ISBN: 1576100561   Pub Date: 10/01/96
  

Previous Table of Contents Next


JDBC Exception Types

JDBC provides special types of exceptions to be used by a driver: SQLException, SQLWarning, and DataTruncation. The SQLException class is the foundation for the other types of JDBC exceptions, and extends java.lang.Exceptn. When created, an SQLException can have three pieces of information: a String describing the error, a String containing the XOPEN SQLstate (as described in the XOPEN SQL specification), and an int containing an additional vendor or database-specific error code. Also note that SQLExceptions can be chained together; that is, multiple SQLExceptions can be thrown for a single operation. The following code shows how an SQLException is thrown:

//---------------------------------------------------------------------------
// fooBar
// Demonstrates how to throw an SQLException
//--------------------------------------------------------------------------
public void fooBar()
    throws SQLException
{
    throw new SQLException("I just threw a SQLException");
}

Here’s how you call fooBar and catch the SQLException:

try {
     fooBar();
}
catch (SQLException ex) {

    // If an SQLException is thrown, we'll end up here. Output the error
   // message, SQLstate, and vendor code.
    System.out.println("A SQLException was caught!");
    System.out.println("Message: " + ex.getMessage());
     System.out.println("SQLState: " + ex.getSQLState());
     System.out.println("Vendor Code: " + ex.getErrorCode());
}

An SQLWarning is similar to an SQLException (it extends SQLException). The main difference is in semantics. If an SQLException is thrown, it is considered to be a critical error (one that needs attention). If an SQLWarning is thrown, it is considered to be a non-critical error (a warning or informational message). For this reason, JDBC treats SQLWarnings much differently than SQLExceptions. SQLExceptions are thrown just like any other type of exception; SQLWarnings are not thrown, but put on a list of warnings on an owning object type (for instance, Connection, Statement, or ResultSet, which we’ll cover later). Because they are put on a list, it is up to the application to poll for warnings after the completion of an operation. Listing 10.1 shows a method that accepts an SQLWarning and places it on a list.

Listing 10.1 Placing an SQL Warning on a list.

//--------------------------------------------------------------------------
// setWarning
// Sets the given SQLWarning in the warning chain. If null, the
// chain is reset. The local attribute lastWarning is used
// as the head of the chain.
//--------------------------------------------------------------- ---------
protected void setWarning(
    SQLWarning warning)
{

    // A null warning can be used to clear the warning stack
     if (warning == null) {
          lastWarning = null;
    }
    else {
        // Set the head of the chain. We'll use this to walk through the
        // chain to find the end.
        SQLWarning chain = lastWarning;

        // Find the end of the chain. When the current warning does
        // not have a next pointer, it must be the end of the chain.
        while (chain.getNextWarning() != null) {
            chain = chain.getNextWarning();
        }

        // We're at the end of the chain. Add the new warning
        chain.setNextWarning(warning);
        }
}

Listing 10.2 uses this method to create two SQLWarnings and chain them together.

Listing 10.2 Chaining SQLWarnings together.

//-----------------------------------------------------------------------
// fooBar
// Do nothing but put two SQLWarnings on our local
// warning stack (lastWarning).
//------------------------------------------------------------------------
protected void fooBar()
{

    // First step should always be to clear the stack. If a warning
     // is lingering, it will be discarded. It is up to the application to
     // check and clear the stack.
    setWarning(null);

     // Now create our warnings
    setWarning(new SQLWarning("Warning 1"));
    setWarning(new SQLWarning("Warning 2"));
}

Now we’ll call the method that puts two SQLWarnings on our warning stack, then poll for the warning using the JDBC method getWarnings, as shown in Listing 10.3.

Listing 10.3 Polling for warnings.

// Call fooBar to create a warning chain
fooBar();

// Now, poll for the warning chain. We'll simply dump any warning
// messages to standard output.
SQLWarning chain = getWarnings();

if (chain  != null) {
         System.out.println("Warning(s):");

    // Display the chain until no more entries exist
    while (chain != null) {
          System.out.println("Message: " + chain.getMessage());

        // Advance to the next warning in the chain. null will be
        // returned if no more entries exist.
        chain = chain.getNextWarning();

    }
}

DataTruncation objects work in the same manner as SQLWarnings. A DataTruncation object indicates that a data value that was being read or written was truncated, resulting in a loss of data. The DataTruncation class has attributes that can be set to specify the column or parameter number, whether a truncation occurred on a read or a write, the size of the data that should have been transferred, and the number of bytes that were actually transferred. We can modify our code from Listing 10.2 to include the handling of DataTruncation objects, as shown in Listing 10.4.

Listing 10.4 Creating dDataTruncation warnings.

//------------------------------------------------------------------------
// fooBar
// Do nothing but put two SQLWarnings on our local
// warning stack (lastWarning) and a DataTruncation
// warning.
//------------------------------------------------------------------------
protected void fooBar()
{

    // First step should always be to clear the stack. If a warning
     // is lingering, it will be discarded. It is up to the application to
    // check and clear the stack.
    setWarning(null);

    // Now create our warnings
     setWarning(new SQLWarning("Warning 1"));
     setWarning(new SQLWarning("Warning 2"));

    // And create a DataTruncation indicating that a truncation
   // occurred on column 1, 1000 bytes were requested to
    // read, and only 999 bytes were read.
     setWarning(new DataTruncation(1, false, true, 1000, 999);
}


Previous Table of Contents Next